Skip to content

feat: add --markdown-tree paginated output for static site generators#700

Merged
robertgendler merged 3 commits into
usnistgov:dev_2.0from
smithjw:feat/docusaurus-output
Jun 21, 2026
Merged

feat: add --markdown-tree paginated output for static site generators#700
robertgendler merged 3 commits into
usnistgov:dev_2.0from
smithjw:feat/docusaurus-output

Conversation

@smithjw

@smithjw smithjw commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Adds mscp guidance --markdown-tree <baseline> (also included in --all), which renders a baseline as a directory tree ready to drop into any CommonMark-based static site generator - Docusaurus, Starlight, MkDocs, VitePress, etc.

Output:

    build/<baseline>/markdown_tree/
        index.md                  # overview - foreword, scope, authors
        02-<section-slug>/
            index.md              # section description
            01-<rule-slug>.md     # one page per rule
        ...

Files are NN- prefixed for stable ordering (no sidebar config needed in the case of Docusaurus). index.md follows the category-index convention recognised by Docusaurus and Starlight. Frontmatter is minimal — title only — so it should work across generators wit minimal modification needed.

Content reuses markdown/rule.md.jinja via a markdown_tree context flag, selecting heading-based Check/Remediation sections and a GFM pipe table for references. The single-file --markdown output path is left as-is.

Also fixes a crash in adoc/rule.adoc.jinja when rule.references.hhs is absent (rules predating the HICP framework).

Tests:
41 pytest tests covering mdx_escape, create_slug, render_references_md, _frontmatter, and an integration test against a real baseline asserting NN- ordering, balanced fences, no raw braces outside fenced blocks, and valid frontmatter. Validated: 104/104 (cis_lvl1) and 168/168 (disa_stig) pages compile under @mdx-js/mdx v3.

Note: --markdown-tree has no short flag to avoid collision with -m/--markdown

image

@smithjw smithjw force-pushed the feat/docusaurus-output branch from b7e4da0 to 250d488 Compare June 12, 2026 10:09
@smithjw smithjw force-pushed the feat/docusaurus-output branch 2 times, most recently from 3fcd4b2 to 53d264a Compare June 20, 2026 00:58
smithjw added 3 commits June 20, 2026 12:52
Adds mscp guidance --markdown-tree <baseline> (also included in --all),
which renders a baseline as a directory tree ready to drop into any
CommonMark-based static site generator: Docusaurus, Starlight, MkDocs,
VitePress, and similar.

Output shape:

    build/<baseline>/markdown_tree/
        index.md                  # overview: foreword, scope, authors
        02-<section-slug>/
            index.md              # section description
            01-<rule-slug>.md     # one page per rule
        ...

Files are NN- prefixed for stable ordering (no sidebar config needed).
index.md follows the category-index convention recognised by Docusaurus
and Starlight. Frontmatter is minimal (title only) so it works across
generators without modification.

Content reuses markdown/rule.md.jinja via a markdown_tree context flag,
selecting heading-based Check/Remediation sections and a GFM pipe table
for references. The single-file --markdown output path is unchanged.
Manual-rule notes use > **Note:** blockquotes that render everywhere.

Tests: 41 pytest tests covering mdx_escape, create_slug,
render_references_md, _frontmatter, and an integration test against a
real baseline asserting NN- ordering, balanced fences, no raw braces
outside fenced blocks, and valid frontmatter. Validated: 104/104
(cis_lvl1) and 168/168 (disa_stig) pages compile under @mdx-js/mdx v3.

Note: --markdown-tree has no short flag to avoid collision with
-m/--markdown.
The concatenated __all__ entry "PLATFORM_MAPvalidate_yaml_file" made
pyflakes miss both names as exports, so it reported their imports as
unused (F401). Splitting it fixes both. Also import CONFIG_PATH so its
existing __all__ entry resolves, drop unused BaseModel/config imports,
and clean blank-line whitespace in scap.py.
@smithjw smithjw force-pushed the feat/docusaurus-output branch from a0906f7 to 7662a76 Compare June 20, 2026 02:53
@robertgendler robertgendler merged commit 5efafb1 into usnistgov:dev_2.0 Jun 21, 2026
4 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants